================================================================
  Tomb Raider: Legend  --  VR mod                    VERSION 1.1.0
================================================================

Please report anything that goes wrong (see REPORTING PROBLEMS at the end)
-- the logs make most problems fixable without needing your PC.

WHAT YOU NEED
-------------
  * Tomb Raider: Legend for PC -- the Steam or the GOG release
  * A PC VR headset with tracked controllers, and SteamVR (or another
    OpenXR runtime that runs 32-bit games)
    (tested on HP Reverb G2; Oculus Touch, Index and WMR bindings included)

The original game files are not modified. The mod adds files beside trl.exe,
and its launcher writes a separate patched copy named trl_vr.exe.


NEW IN 1.1.0
------------
  * OpenXR, with OpenVR as the fallback. The mod uses OpenXR by default and
    falls back to OpenVR / SteamVR if OpenXR cannot start. Delete
    openxr_loader.dll (or set vr_runtime = openvr) to always use OpenVR.
    The main menu shows the version and the runtime in use.
  * A settings panel in the headset: hold both sticks in for 0.6 s
    (Oculus Touch: hold the left menu button), or press Insert. Point at it
    with your main hand and pull the trigger, or use the sticks and A / B.
    Changes apply at once and are saved to trlvr.ini.
  * TR7-Menu-Hook's options are built into that panel when it is installed:
    refill health, next outfit, game speed, wireframe, hide UI, debug
    keypad and its saved settings.
  * God mode (board view): pinch or make a fist on Lara to pick her up,
    carry her and throw her by letting go mid-swing.
  * Body physics: her chest and rear give and bounce in third person, and a
    hand leaning on her in god mode pushes her body away.
  * Smooth glide when switching camera style.
  * Picture brightness and contrast for the headset (settings panel).
  * The palm sliders gain a third bar that moves the camera left or right
    (over either shoulder). Each camera style keeps its own size, zoom and
    side; a notch marks each default and the knob sticks there. Your index
    fingertip can now grab the knobs as well as your palm.
  * Movies are shown at their real 4:3 shape.
  * Smoother play with some player model mods.


------------------------------------------------------------
1. PREPARE THE GAME
------------------------------------------------------------
Run Tomb Raider: Legend normally once, reach the main menu, then quit.

Open the game's Setup dialog and turn OFF:

    Next Generation Content     (its renderer gives a black scene in VR)

The mod sets three other options itself at every start, whatever the Setup
dialog says (trlvr.ini, [vr]):

    depth_of_field = off        blurs the distance in VR
    fullscreen_effects = off    flat-screen glow that smears the two eyes
    fsaa = on                   anti-aliasing, its strength capped by msaa

Set any of them to "game" to keep the Setup dialog's choice instead.


------------------------------------------------------------
2. INSTALL
------------------------------------------------------------
Copy everything inside

    Main - Copy these into the base game folder

into the folder containing trl.exe. Steam's default is:

    C:\Program Files (x86)\Steam\steamapps\common\Tomb Raider Legend

GOG RELEASE: GOG ships its own D3D9.dll (a compatibility wrapper) in the game
folder. Rename it first, for example to D3D9.dll.gog-dxwrapper, then copy the
mod's files in. Rename it back to uninstall.

Any other d3d9.dll in the folder belongs to another graphics mod; move it
aside -- two D3D9 mods cannot load under the same filename.


------------------------------------------------------------
3. HOW TO START
------------------------------------------------------------
STEAM: right-click the game > Properties > Launch Options and enter

    "C:\Program Files (x86)\Steam\steamapps\common\Tomb Raider Legend\trlvr_launcher.exe" %command%

(adjust the path if the game is elsewhere), then start SteamVR (or your
OpenXR runtime) and launch the game from Steam as usual.

GOG: start SteamVR (or your OpenXR runtime), then run trlvr_launcher.exe from
the game folder (make a shortcut to it if you like).

The launcher makes trl_vr.exe, a large-address-aware copy of the game: this
2006 32-bit game otherwise runs out of memory at headset resolution.

On first start the mod writes trlvr.ini (your settings) and trlvr.log beside
the game. Settings are read at start-up: quit the game, edit, start again.


------------------------------------------------------------
4. MODES -- THIRD PERSON BY DEFAULT, FIRST PERSON OPTIONAL
------------------------------------------------------------
A fresh install plays in THIRD PERSON with immersive controls on and the
radial gear menu (click the left stick, push towards an item). Long-press
the right stick to step through the camera styles -- classic, shoulder,
board -- and first person. For the plain button layout of the game instead,
set immersive_controls = 0 (the table below).

FIRST PERSON IMMERSIVE (recommended for testers once you are settled):
open trlvr.ini and set

    [vr]
    first_person = 1
    first_person_tracked_hands = 1

    [controls]
    immersive_controls = 1

  first_person only picks the view you start in: with immersive controls on,
  long-press the right stick (or press \ on the keyboard) to switch between
  first and third person at any time in gameplay.

You then see through Lara's eyes with your own tracked hands:
  * Pistols: reach to a hip and lift to draw; hold the gun back at the hip to
    holster. Reach over a shoulder and grip to swap to the long gun.
  * Gear: grapple, binoculars and light hang on your belt -- grab them with
    either hand. Grenades/flares and medipacks sit in pouches, shown as the
    game's own models while you carry any.
  * Climbing: grip a ledge, vine, chain or bar with your hands and pull your
    body along it. Pull down with both hands to climb up onto a ledge.
    Alternate hands quickly to shimmy fast. One-hand catches: grab the hold
    (or set auto_secure_catch = bars or all to have them secured for you).
  * Crouch for real to crouch. Jumping off a chain goes where you look.
  * Pause menu > "VR Settings" (the old Display menu). Each entry changes a
    VR option on the spot and saves it to trlvr.ini:
      Theatre            Off / Cutscenes / Always
      Third Person       Classic / Shoulder / Board / All
      Hand Collision     Off / On / On + Body
      Body               Hands / Full
      Left Handed        Off / On
      Hardcore Mode      Off / On
    (The On/Off column on the right still shows the game's own setting; the
    label is what counts.)
      "VR Holster Setup" (the old Widescreen entry) places the holsters,
      gear and pouches where they suit your body.
      "Hand Calibration" (the old Next Generation Content entry):
        Step 1, hand alignment: Lara's hands are held out in front of you.
        Move each controller to where it should sit in that hand and
        squeeze its grip to lock it; locking both saves.
        Step 2, pistol aim (first person): point your pistol at the target
        ahead the way you would aim it and pull that trigger. Saved for
        both hands (your gun hand is the right, or the left with
        left_handed = 1).
        A skips a step and keeps what you had; the menu button stops.
        Do this first if her hands or your aim do not line up (common on
        Quest).

Other camera options (third person, immersive controls on):
    third_person_mode = classic | shoulder | board | all
  (all: the right-stick long press cycles classic, shoulder, board and
  first person in turn)
  board = Lara a few inches tall on a tabletop world; with board_god_hand = 1
  you can pick her up, stand her on your palm and flick her over (hold Y).

Optional body:  first_person_body = full   (whole body instead of hands only)

Third person extras: turn your off hand palm up for three sliders -- the
size of the world, the camera nearer or farther, and the camera left or
right of Lara. Touch a knob with your other palm or index finger, grip and
slide. Each camera style keeps its own; a notch marks each default. Walking
beside a wall with nothing drawn, Lara runs her hand along it (wall_touch).

SETTINGS PANEL: hold both sticks in for 0.6 s (Oculus Touch: hold the left
menu button), or press Insert on the keyboard. Cameras, picture, body
physics, god mode, theatre, diorama and controls are all there, plus
TR7-Menu-Hook's options when it is installed.


------------------------------------------------------------
VR CONTROLLERS (classic layout)
------------------------------------------------------------
    Left stick                 move
    Left stick click           gear menu: push the stick towards an item --
                               up health pack, right binoculars,
                               down switch weapon, left personal light
                               (in menus: back)
    Left stick double click    recenter the VR view
    Left stick long press      pause (Esc)
                               (Oculus Touch: the left menu button)
    Both sticks held in        settings panel
                               (Oculus Touch: hold the left menu button)
    Right stick                turn
    Right stick click          switch weapons
    Right stick double click   open the PDA
    Right stick long press     binoculars
    Left trigger               action / interact / pull grapple
    Right trigger              fire; select in menus
    Left grip                  throw grapple
    Right grip                 combat lock-on
    A                          jump / surface; select in menus
    B                          dive / crouch / roll; back in menus
    X                          accurate aim
    Y short press              grenade / flare
    Y long press               personal light

A long press is 0.65 seconds. VR CONTROLLER BINDINGS.txt has the per-headset
details. Under OpenVR, if SteamVR keeps an old custom binding, open SteamVR >
Settings > Controllers > Manage Controller Bindings and pick the supplied one.
Under OpenXR the bindings are built into the mod.

Keyboard: F1 recentres the view. The game's own keys still work.


------------------------------------------------------------
PERFORMANCE
------------------------------------------------------------
Aim for a steady frame rate rather than the highest resolution:

  * SteamVR > Settings > Video > per-application resolution for the game.
    Restart the game after changing it. 100% first; 80% if it struggles.
  * If 90 fps is out of reach, SteamVR's per-application throttling at a
    fixed half rate with Motion Smoothing usually feels smoother than a
    frame rate that keeps jumping.
  * trlvr.ini, [vr]:
      msaa = 4                       anti-aliasing strength: 0 (off), 2, 4, 8
      fsaa = off                     anti-aliasing off altogether
      first_person_object_culling = frustum   (open = draw everything)
      terrain_culling = frustum                (open = draw every terrain strip)
    The "open" settings exist only in case something visibly pops in or
    vanishes; they cost a lot of CPU. In game, F2 switches object culling and
    Shift+F2 terrain culling for a quick comparison.
  * Turning off Water Effects, Reflections and Shadows in the Setup dialog
    gives a little more headroom on slower PCs.

The mod writes a "perf:" line to trlvr.log every 5 seconds. If an area runs
badly, mention roughly where and when -- the log says why.


------------------------------------------------------------
SETTINGS WORTH KNOWING (trlvr.ini)
------------------------------------------------------------
Every setting has a short explanation in the file itself. Missing settings
are added on start-up; values you chose are never replaced.

  [vr]  vr_runtime              auto / openxr / openvr
        first_person, first_person_tracked_hands, first_person_body
        third_person_mode       classic / shoulder / board / all
        comfort_vignette        off / jumps / full (darkens the view edge)
        physical_crouch         crouch for real to crouch
        auto_secure_catch       off / bars / all: one-hand catches secure
                                themselves on swing bars, or everywhere
        first_person_no_spread  shots go exactly where the gun points
        ui_scale, hud_follow    size and head-follow of the HUD
        cutscene_mode           normal / theatre (gameplay_theatre = 1 too)
        roomscale               walk in your room (first person)
        finger_tracking         Lara's fingers follow yours (Quest, Index)
        first_person_hardcore   the view turns with Lara through flips
        wall_touch              third person: her hand along walls
        body_rear, body_push    third person / god mode body physics
        picture_brightness, picture_contrast    the headset image
        depth_of_field, fullscreen_effects, fsaa     off / on / game
  [controls]
        immersive_controls      gestures, holsters, hand climbing
        left_handed             swap the main hand
        pistol_mode             akimbo / single
        aim_mode                hand / hands / hands_head
        turn_mode               smooth / snap  (snap_turn_degrees)
        hand_collision          hands stop at walls and floors
        gear_menu               cross / radial (immersive third person)

To start over with all defaults, rename trlvr.ini and start the game once.


------------------------------------------------------------
KNOWN LIMITATIONS
------------------------------------------------------------
  * Next Generation Content is not supported (black scene). Keep it off.
  * Water reflections and the full-screen water effect are skipped (they only
    exist for one eye), so deep water looks flatter than on a monitor.
  * Graphics options can only be changed in the Setup dialog (or with the
    trlvr.ini settings above): during a level the in-game Display menu is
    the VR Settings menu instead.
  * Cinematics play in third person on a world-locked view.
  * Some original wet-rock "sheen" decals flicker by view angle -- the flat
    game does the same.


------------------------------------------------------------
REPORTING PROBLEMS
------------------------------------------------------------
Please describe what happened and roughly when, and send these files from the
game folder (whichever exist):

    trlvr.log            this session
    trlvr.log.prev       the session before (kept when you relaunch)
    trlvr_crash.dmp      written if the game crashes (and .prev)
    trl_vr_d3d9.log      the graphics backend log

A screenshot from the SteamVR mirror helps with anything visual.


------------------------------------------------------------
UNINSTALL
------------------------------------------------------------
Clear the Steam launch option (Steam) and remove these files from the game
folder; GOG: rename D3D9.dll.gog-dxwrapper back to D3D9.dll.

    d3d9.dll   d3d9_dxvk.dll   openxr_loader.dll   openvr_api.dll
    trlvr_launcher.exe
    trlvr_actions.json   bindings_*.json
    trlvr.ini   trlvr.log*   trlvr_crash.dmp*   trl_vr.exe
    trlvr_launcher.log   trl_vr_d3d9.log
